The Original Shareware 1.1

home *** CD-ROM | disk | FTP | other *** search

/ The Original Shareware 1.1 / The Original Shareware (WeMake CDs)(Volume 1.1)(CDs, Inc)(1993).iso / 36 / spawn15.zip / SPAWN.DOC < prev next >

Wrap

Text File | 1990-11-01 | 26KB | 525 lines

Spawn Version 1.5 Public Domain by Albert H. Ariail Copyright 1990 The following program is a Desqview specific utility to allow you to execute a more or less arbitrary DOS command in the background. This program nicely implements what someone has called "the compile in the background circus trick". The background process inherits the default directory and the environment that was in effect when spawn was invoked. Spawn will execute any DOS internal or external command that does not require operator intervention and is otherwise compatible with Desqview. Another useful application is to use spawn to force full screen programs to load into their own windows. This makes working in a small DOS window much easier. Hardware/Software requirements: IBM PC/XT/AT or 100% compatible running DOS 3.x and Desqview 2.x . A 386 processor is not specifically required, but you will certainly get a lot more out of this program if you have one. **************************************************************************** * If you have any problems, questions, comments, etc about this program, * * Please feel free to contact me. My Compuserve user id is [73510,2562] * **************************************************************************** If you are new to Desqview, the following definitions may help make this documentation more intelligible. I will use the term "parent process" to refer to the Desqview window from which you invoke spawn. It is the function of spawn to open a new Desqview window to execute the supplied command. This will be called the "child process". A process is in the foreground when it can receive input from the keyboard, otherwise it is in the background. Foreground windows are always visible, background windows may or may not be, depending on whether or not they are behind other windows. The PIF file for a window is the Desqview Program Information File that is used to tell Desqview more about the program that is to be executed. When you are manipulating the "Change Program" menu, you are editing the PIF file for that entry. Under Desqview, a process that is invoked with the keys "XX" will have a PIF file of c:\dv\xx-pif.dvp . Installation Instructions: This program assumes that the Desqview executable and all of your PIF files reside in the directory C:\DV . If this is not the case, before starting Desqview, you should set the environment variable DESQ to point to the correct pathname, e.g. c> set desq=e:\desqview In what follows if I use the directory c:\dv, I will be referring to either this directory or whatever is in the variable DESQ . After unpacking the archive file, copy file files sp-pif.dvp and dvcmd.com to the current Desqview directory. dvcmd.com file must be present in c:\dv and not renamed. sp-pif.dvp is the Program Information File that spawn uses to launch the new process. This may be renamed if you specify the correct (complete) pathname in the environment variable SP-PIF . SP does not have to be present in your Desqview "Open Process" menu unless you wish to change the default settings. The program spawn.com can reside anywhere accessible from your current PATH variable. Update information: If have an earlier version of spawn, here some of the features included with this release. New options: /r - remain in dos /z - exit with bkgd operation disabled /e - exit with bkgd operation enabled /n - output child's "process handle" New environment options: SP-CMD The ability to operate outside of desqview (after a fashion). Reworked spawn "command|command". Does not feed keyboard. Repaired some minor bugs, mostly, involving spawn/p:xx not starting properly with certain PIF configurations. Utility programs kill.com - shutdown desqview windows release.com - pass a return code to spawn. dvtest.com - test for the presence of desqview in a batch file alert.exe - general purpose message utility Basic operation: To invoke a command in a background window, simply enter: c>spawn program [arguments] where program is any valid DOS internal or external command with whatever arguments it expects, e.g., c>spawn copy c:\dv\*.* a: If you are executing an external command (a .COM or .EXE file) you can save about 5K of memory in the child process if you specify a complete pathname for "program" : c>spawn c:\bin\pkzip.exe -par e:\archive c:\*.* instead of c>spawn pkzip -par e:\archive c:\*.* You can also spawn off pipes and filter programs by enclosing the command in quotes: spawn "dir *.* | sort >sort.dat" Note that spawn "dir *.* >dir.dat" is completely different from spawn dir *.* >dir.dat The latter will put the output of spawn in the file dir.dat (usually there is no output from spawn itself, so dir.dat will be empty). Environment variables used by spawn: CMDSWT - Defines text which will be placed on the command line whenever spawn invokes command.com. This is usually assigned to a string such as CMDSWT=\e:1500, which for DOS 3.2 or 3.3 will give some additional free space in the child's environment. SP-MEM - Defines the amount of memory to be given to the child process e.g., SP-MEM=256 will grant 256k bytes of free memory. If specified, this will override the memory allocation defined in sp-pif.dvp which initially is set to "all you can get". SP-PIF - Defines the Desqview Program Information file used by spawn. The default is c:\dv\sp-pif.dvp . You must specify a complete DOS pathname if this is used (for example: c:\desq\spawn.pif or c:\dv\xx-pif.dvp). DESQ - Defines the pathname to the desqview directory. If not specified, c:\dv is assumed. dvcmd.com must reside in this directory. If the PIF file name has not been changed as described above, sp-pif.dvp must also be in this directory. COMSPEC - This defines the program name which is used to invoke "command.com" As you probably know, this is generally set by DOS at boot up and is rarely changed by the operator. SP-CMD - This option is only used outside of desqview. It defines an alternate command processor to be used to execute the specified command. Its primary function is to cause spawn to invoke the program SWAPDOS(tm) when executed outside of desqview. See below. The following environment variables are set in the child (overriding any previous definition). CMDLINE - The command and parameters to be executed. PARENT - This is a Desqview task handle for the parent, which is an 8 byte hex number in the format ?dead0000. The ? is included obscure for semantic reasons known only to me. This is used by the utilities kill.com and release.com to find the parent process. Run time options: Note: all of the options below must be placed immediately after the command name "spawn" or they will be assumed to be options for the command being executed, e.g., spawn/f copy ... /a - alarm at completion This options causes the child process to pause at completion. If running in the background, the child process will be placed in to the foreground. This allows you to review any exit conditions from the spawned command. To acknowledge the message, key ESC or click the mouse. /s - silent alarm same as /a but less noisy. /f - move child to foreground Normally the child process is executed in the background. This will force the parent into the background and let the child continue running in the foreground. /w - suspend parent until child completes This will stop the parent until the spawned command completes. You may manually restart a waiting process by keying ESC . Normally you will want to use this switch in conjunction with /f. This option also gives allows you to retrieve a DOS program return code from the spawned process (see below). /d - disable background operation in parent When used with /f, this switch will also suspend the parent until the child completes. This suspend is softer than /w , the parent process will restart automatically the first time you switch to it. /r - remain in dos spawn always sets the pif field "close window on exit" to "y" . If you want to stay at the DOS prompt at the end of the spawned command, you must specify /r . When this switch is used with /a or /s, the alarm is not sounded until you enter "exit". /z - exit with background operation disabled Some of the options (/x) work a bit more smoothly if the parent has "runs in the background" set to "y". Spawn will automatically enable background operation for you, but, as a rule, will leave it that way. This is not much of a problem if you are executing spawn from a DOS window, but can be troublesome if you are using spawn with a program which writes directly to the screen. The option /z tells spawn to always exit the parent with background operation disabled. /d also disables background operation, but will re-enable it when spawn completes; /z does not. /e - exit with background operation enabled This is the exact opposite of /z and is included mainly for completeness. It may be useful at times in conjunction with the program alert. Alert/d works best if the foreground window has background operation enabled. If you are spawning off a batch file which calls alert, you can use this switch to guarantee this is so. See the Utilities documentation for more information on alert. /x - move parent to foreground at exit This will guarantee that the parent returns to the foreground after the child exits. This is normally used in the combination /w/f/x or /d/f/x to insure control returns directly to the parent and not to some other process. This switch does not work properly if you also specify /z . /p:xx - use alternate pif This defines the PIF file to be used in lieu of the default file sp-pif.dvp . This option will also override the environment setting SP-PIF. This should be used if the program being spawned requires special Desqview options in order to function. This switch /p:ab is short for /p:c:\dv\ab-pif.dvp . You may specify a complete pathname if you wish. The specified file must be a valid Desqview Program Information File, but does not have to be present on the Desqview "Open Window" menu. /m:n - limit memory to n K This provides another way to control the amount of memory the spawned process acquires. /m:256 will give the process 256k of memory. This switch overrides the setting in the specified pif file as well as the environment variable SP-MEM . (see below) /n - This outputs the task handle of the child to stdout. You can redirect this to a file as in spawn /n ... >child This file can then be used with kill.com to close the child's window, eg, kill child . See the Utilities documentation for more information. Notes and Ideas: 1. Watching the spawned process execute. You can of course use spawn/f, but this sort of defeats the purpose of using spawn. A more elegant way is to open as small DOS window such as D1, move it out of the way and enter something like: spawn/p:d1/f/x copy *.* a: The function of the switch combination "/f/x" is to keep the parent process in the foreground and not allow the child's window to be hidden behind other windows. 2. Using script files with spawn. I recommend that you do not attach a script to sp-pif. If you want use a script with a spawned process, use /P:XX to specify a PIF file that has a script file attached to it. The script file used is not determined by the file name, but rather the field "Keys to use on open menu" . If this is say, AB, and a script file c:\dv\ab-scrip.dvs exists, Desqview will play it back in the child process when spawn starts it. You must use /f to be sure to new process starts in the forground, since otherwise, the script will play back in the wrong window. 3. Getting more environment space in the child process. If you spawn off batch files that manipulate the environment with the DOS "SET" command, you may get "out of environment space" errors from command.com . For DOS 3.2 and 3.3, you can fix this by setting the environment variable CMDSWT=\e:nnnn where nnnn is the number of bytes you which to allocate to the new environment. This text will be placed on the command line whenever spawn invokes command.com . For earlier versions of DOS, you will need to set up some long dummy environment variables in the parent window (or better, before you start desqview) such as set a=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa set b=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb At the beginning of the batch file that you wish to spawn, clear these variables with set a= set b= This will generally free up enough space for the batch file to continue normally. 4. Specifying the memory to be given to the child process. Initially, the spawn PIF file is configured to allocate as much process memory as is available for the child process. While this is the most general, it is usually far too generous. For most of the programs that you would use will spawn, 256K is more than enough. You can always modify sp-pif.dvp to scale back it maximum memory allocation, I recommend that you instead set the environment variable SP-MEM=256 . This will have the same effect, but can be changed more readily. The SP-MEM setting is overridden by /m:nnn on the command line and is ignored when you specify an alternate pif file with /p:xx . Spawn will modify the "maximum program memory size" field of the pif file. If the "memory size" is greater than the "maximum memory" both are set to the specified value. In all cases, 8k is added to both fields to help accommodate spawn overhead If you specify the program with a full pathname and do not have a large environment, the overhead in the child will be only about 4k. If you are trying to conserve memory, you can use a /m:n switch to reduce this adjustment. 5. Modifying SP-PIF.DVP Spawn itself is not very sensitive to the set up of the PIF file (as long as there is sufficient memory to start the child process). Spawn will modify the various fields if it needs to. In particular, the following are always replaced by spawn: Program name Program parameters Directory Close on exit (always set to yes) Anything placed in these fields will never be used. As I have mentioned, the process SP does not have to be in the Desqview "Open Window" in order for spawn to function. So after making whatever modifications desired, you may delete the menu item "SP". You must then rename the file sp-pif.bak to sp-pif.dvp in order for spawn to be able to find it. Spawn will occasionally adjust other PIF parameters. If, for example, you use spawn/p:xx to execute something in the background, spawn assumes that you intend for it to execute, and will set "runs in the background" to "y" 8. Flicker during startup. One possible modification to sp-pif that you may wish to consider is changing the starting height,width to 1,1 and initial position to 1,78 . These settings help to minimize the brief flicker that occurs when the spawned command starts and completes. At least, it moves it to the upper right hand corner of the display where it is less obtrusive. Of course, if you latter wish to switch to the "spawn" window, you will have to zoom it to full size in order to see anything. 7. Getting the DOS return code from a child. When spawn is used with /w, the normal program return code of the child process is returned by spawn to the parent. This can be used with an "if errorlevel" test inside of a batch file. The return code will correct when following conditions are met: a. spawn was executed with the /w option and not /r b. a complete pathname was given for the executable command You can use the utility release.com to bypass this rule and return an exit code from a batch file. c. the command was not enclosed in quotes Again this does not apply to release.com d. the wait was not aborted with ESC in the parent or a "close window" command in the child If (d) fails, or some other error occurs, spawn will return a value of 255. Otherwise spawn will return a condition code of 0. 8. Using spawn to force a context switch. Some text editors have the ability to run a compiler or assembler while the user remains inside the editor environment. Since the editor is still in memory, the total ram that is available to the compiler is limited. If the editor can be configured to invoke the compiler with something like spawn /w/f/p:bd c:\cc\tcc.exe ... then the compiler will run in its own window with a full compliment of memory. The /w switch is appropriate here since the editor must wait for the compilation to complete before continuing and may need the correct return code from tcc.exe . This sort of thing can also be done from a batch file so that full screen editors and the like can be conveniently run from a small Desqview window. For example, if you have an editor say edit.exe, you can create a one line batch file, say ed.bat, containing @spawn/d/f/x/p:ed c:\bin\edit.exe %1 %2 %3 %4 %5 %6 %7 %8 %9 The /d will disable the DOS window while the editor is running, but unlike /w, /d will allow the DOS window to restart the first time you select it. The /x will assure that DOS regains control when the editor finishes. Without the /x, if you were to pull up a third window while in the editor, control of the keyboard would pass to this window when you exit the editor. Finally, the switch /p:ed selects a pif file appropriate to the editor. 9. Transferring the child's console output back to the parent. Some text editors have the capability to executing a program, such as a compiler and capturing the console output, which is displayed in various ways. If you wish to use something like this with spawn, you will need to start a batch file such as: if "%1"=="*" shift if "%0"=="*" goto child spawn/w/f/x "%0 * %1 >desqtmp.$$$" type desqtmp.$$$ goto quit :child masm %1; ... The value of the variable %1 is assumed to be the filename to be processed and is supplied by the editor. %0 is set by command.com to the name of the batch file being executed. Its presence in the spawn command cause spawn to reinvoke the same batch file for the child. So the child can know which is which, a "*" is placed in the first slot. The function of the first two lines is to test for and get rid of the "*". It may seem that it would be more efficient to invoke a different batch file for the child. Actually, if you use a disk cache, this method is probably faster, and even if not, it makes things a bit easier to manage if everything is kept together. 10. If you do not have a 386 processor. You can still use spawn for context switching with a non-multitasking system. In this case, the parent process will swap out when spawn is invoked. You will generally want to use /f so that the parent isn't swapped back initially. If the current process is marked non- swappable and there isn't sufficient conventional memory to load the child process, then spawn will fail with the message "api error activating new process". If you want the child process to run concurrently with the parent, you must lower the "maximum program memory" in the parent window to a value small enough so that there is sufficient free conventional memory to hold both processes. The exact amount will vary, but a figure of about 180k will permit one 180k process to spawn. 11. If you are running 4dos *** You can spawn off multiple commands using the usual 4dos logical end of line character: "^" as in spawn "command^command" The quotes are required. Spawn and 4dos both make use of the environment variable "CMDLINE". This should not be a conflict, since we are both using this variable to mean the same thing. At present, spawn does not support arguments greater than 127 bytes. With version 2.2 and below, 4dos passed the alias list with the environment, which meant that the child would inherit the aliases that where in effect when spawn was invoked. Starting with version 3.0 of 4dos, the alias list is kept out of the environment, so the child process gets whatever aliases that were in effect when desqview started. This will probably work better, since you can set up a general purpose alias list as part of your desqview startup procedure. The child process will receive the general purpose aliases rather than the parent's, which may be only appropriate for, say, small windows. If you wish to force the child to get an updated alias list, you may uses the alias /r command of 4dos , for example: in parent: alias >desqtmp.$$$ spawn ... in child: alias /r desqtmp.$$$ *** If you are not using 4dos (tm), it is a shareware replacement for command.com by Rex C. Conn and Tom Rawson. Together with Desqview, it is one of the best DOS enhancement programs ever. It is, of course, fully compatible with Desqview. I cannot give this program a higher personal recommendation. 12. SP-CMD and Behavior outside of Desqview. If spawn is invoked without the presence of desqview, all of the options are ignored and the command is processed by calling a secondary copy of command.com . This may be useful on occasion, given the processing of the CMDSWT environment variable, but the primary reason for including this feature is so that you may imbed spawn into such things as text editor "shell" commands without having to change configurations when you are outside of Desqview. There is a small price to pay for this convenience: about 6k of memory. You can use SP-CMD to control what program is invoked to execute you command. For example, if you are using 4DOS, but want spawn to execute command.com you could set sp-cmd=c:\command.com /c A full pathname and the "/c" are required. The CMDSWT variable is still used and is inserted as usual, just before the "/c". A much more useful application of this feature is to have spawn invoke SWAPDOS *** . You will have to learn the ins and outs of this program for yourself, but I have found that using the "long" method seems to work better on my system. That is, sometime before invoking the program which will be swapped, run swapdos /m to mark the current memory configuration, then use swapdos /l . If you have spawn commands imbedded in an editor, you can make this automatic with set sp-cmd=c:\bin\swapdos.com /l If you are using quoted commands with spawn to redirect the child's stdout, etc, you will need to use set sp-cmd=c:\command.com /c swapdos /l so that command.com will be invoked to process the redirection. At this time, SP-CMD is not supported inside desqview because of conflicts with other features. *** SWAPDOS (TM) is a shareware product by Nico Mak and distributed by Innovative Data Concepts. It is used to free up memory when shelling out of an application such as a text editor. 13. Misc As mentioned, spawn will set up the current default drive and directory in the child. This only occurs on the default drive. Other drives will keep the default directory information that was in effect when desqview started. If you start a background process from a window which has "share cpu" set to "n", the spawned process will be suspended as soon as it starts. This is, after all, what this setting means. I have attempted to smooth out these types of things, but in this case, Desqview doesn't give me the ability to take corrective action. 14. Trademarks, etc Desqview is a trademark of Quarterdeck Office Systems. MS-DOS is a trademark of Microsoft Corp. IBM and IBM PC are trademarks of IBM Corp. 4dos is a trademark of J & P Software. Swapdos is a trademark of Nico Mak and/or Innovative Data Concepts. While I genuinely believe that this program performs as advertised, and will make every effort to see to it that this remains the case, you must assume responsibility for its operation, proper or improper. Considering the price, I think that's a pretty good deal.